Configuring and sending email in Deacom

The use of email features in Deacom is optional. The following email options are available:

  • Email documents and files that have been attached to various Deacom records.
  • Email lot information via lot implosion reports to contacts indicated on Ship-To records. This is very useful in the event of product recalls.
  • Create/sync contacts located in the CRM section of Deacom with a user's MS Outlook account.
  • Email information based on Trigger conditions and setups. Trigger emails are separate from the other email options in Deacom and have their own separate fields and configuration steps. This page deals with the three options listed above. See the Configuring Triggers page for details on using email with Triggers.

Email Configuration Overview

Email configuration involves defining the authentication type that will be used and populating email user, email password and other related information.

There are two authentication types offered in Deacom: Basic and OAuth2. OAuth2 is designed to provide an additional layer of authentication.

  • With Basic authentication companies can use the first two features in the above list: 1. email documents and files, and 2. email lot information from lot implosion reports.
  • With OAuth2 authentication companies can use the first two features in the above list and the sync contacts in CRM feature.

Basic authentication setup

  • Fill out all the fields indicated in the sections below.

In System > Options > Authentication tab

  • Outlook Authentication Type: Ensure "Basic" is set in this field. Basic supports the majority of email providers such as Gmail, Mailgun etc.
  • Email Host - Defines the SMTP server name used for the default email host. Example: mail.company.com
  • Email Port - Defines the port for the default email host. Example: 25.

In Main Menu > User Icon > Email Settings

  • Email - indicates the email (MS Outlook, Gmail, etc.) address of the user currently logged in, i.e. "[email protected]". This email must be registered on the email server/service defined in System > Options > Company tab.
  • Email User - If using Office 365, the "Email User" field must match the email address entered in the "Email" field above, i.e. "[email protected]". If using an internal exchange server, the "Email User" field must be the domain login name or the Outlook User name, i.e. "jsmith" (outlook) or "companyhq\jsmith" (domain).
  • Email Password - The "Email Password" is the password of the email user in the field above. This may or may not be the same as the password used to log on to your computer/network.

Notes:

  1. The remaining fields on the Email Settings form are optional.
  2. The Email Setting section above will need to be completed for each user that will email from Deacom.

OAuth2 authentication setup

  1. Set up and configure Azure as listed in the section below. Note there is an additional option to use secrets with Azure SSO. This is described in Setting up Azure for secrets section on this page. The configuration in the Setting up Azure section below will still need to be performed if choosing to use secrets.
  2. Fill our or verify the information in all the fields listed in the last section entitled "Configuring Deacom for Azure email SSO"

Setting up Azure

Customers will most likely need to coordinate with their IT department for this step. The screens below are taken from an in house system used for demo purposes.

  1. Navigate to the Azure AD admin center (via your apps area in Microsoft 365 or directly via portal.azure.com)
  2. When setting up Azure for the first time, you will be directed to the home page. In the middle of the page, in the "Azure services" section, you con click on the click the "More services" arrow located to the right.
  3. At this point the easiest option is to use the search box (with Filter services inside) at the top of the screen and type in "App registrations".
  4. Click on "App registrations". You should be presented with the screen below.

  1. Click on "New registration" in the top left of the menu.
  2. Enter information as below:
    1. In the Name field, enter the desired name for the application. While the name is not used in the application, it might be helpful for IT Admins to be able to distinguish that it’s for Deacom.
    2. Check the box that indicates Accounts in this organizational directly only (Single tenant)
    3. In the Redirect URL section* - select "Single-page application (SPA)" and then next add the URL/link of the Deacom system you are using. For customers, this will be their test and/or production systems. Example syntax: https://documentaiton.deacom.com/doc1703
      1. *In Azure the Redirect URL option is listed as optional but is required for the Deacom setup.
    4. Your screen should now look similar to one below.

  1. Next, click "Register" at the bottom of the screen.
  2. You will be presented with a screen similar to the one below.

  1. From the screen above copy the "Application (client) ID" and the "Directory (tenant) ID" and paste them into the "Outlook App ID" and "Outlook Tenant ID" fields respectively in the System > Options > Email tab area of Deacom as seen in the screen below. Once you are done hit the "Save" button.

  1. Verify the redirect URL is correct. Click on the "Manage" option on the left hand menu or use the search bar to go to the "Authentication" section. Verify the Redirect URL that was configured earlier in these instructions is displayed.
  2. Setting up API Permissions. On the left hand menu (under the "Manage" folder) there is an option for "API Permissions". While it is possible to add or verify API permissions at this point, the easiest way is to send an email from within Deacom and when prompted to accept the necessary permissions. This tends to be the more accurate method. That process is:
    1. Log onto the Deacom system associated with and configured for the Azure account. (If you are already logged in, please refresh the browser where the Deacom system is running to ensure the System > Options changes from above are applied.)
    2. Select one of the various options in Deacom to email an attachment. For example:
    3. Navigate to Print Outs > Picking Lists.
    4. Select a pick list and click "Print One" on the toolbar.
    5. On the Copies To Print form select "Email" from in the Print To field and click "Print".
    6. The Send Email form will be displayed. Enter an appropriate email address in the To field and click "Sent Email".
    7. You will be presented with a screen similar to below. You should recognize the email account as the one setup previously.
  1. Select the appropriate email account.
  2. You will be presented with the screen below requesting the appropriate API Permissions.
  1. Click "Accept" (You will not be presented with this screen again)
  2. Allow the system to process the email.
  3. Verify the email was sent to the correct email address.
  4. The process is complete.

NOTE: The following URL may be helpful in validating your connection to see if any issues are Deacom related or MS Exchange issues:  https://testconnectivity.microsoft.com/tests/O365EwsTask/input

Setting up Azure for secrets

Customers will most likely need to coordinate with their IT department for this step. The screens below are taken from an in house system used for demo purposes.

There is another way to authenticate by using secrets which has become popular. If this option is selected, the authentication process is handled in the background (based on configuration in the Azure admin center) and does not require interaction or email credentials to be entered when sending emails from Deacom.

  1. Ensure all the steps in the "Setting up Azure" setting above have been completed.
  2. In the Azure admin center, on the left hand menu (under the "Manage" folder) click the "Certificates & secrets" option.
  3. Select the "+New client secret" option.
  4. Enter a description for the secret and expiration time frame in the Expires field. (Note that IT administrators will need to be aware of this time frame so they may add/update the secrets and expiration details)
  5. Click Add. Your screen should look similar to the one below. Do not leave or refresh this page and continue with the steps below. The secret value will only be visible once.

  6. Copy the information in the "Value" field, not the "Secret ID" field and place that in the Outlook Secret field in the Deacom system via System > Options > Email tab. Be sure to save your changes in Deacom.
  7. Back in Azure, click on "API Permissions" on the left hand menu.
  8. Click "Add a permission".
  9. On the Request API Permissions form, click "APIs my organization uses".
  10. In the filter box at the top type Office 365 Exchange Online
  11. Click Office 365 Exchange Online
  12. Click the Delegated permissions option.
  13. You will need to select the four permissions below. You may do this by expanding the corresponding option or by typing the API permission in the Select permissions search bar at the top.
    1. EWS.AccessAsUser.All
    2. Mail.Send
    3. Mail.Read
    4. MailboxSettings.Read
  14. Once all the permissions have been selected click the "Add permissions" button at the bottom. Your screen should look similar to the one below

  1. After these changes have been made in Azure, you will need to refresh the browser where the Deacom system is running to ensure the changes have been applied.

Configuring Deacom for Azure email SSO

Once Azure is setup enter or verify the information in the Deacom fields listed below. Be sure to save after you have entered information.

In System > Options > Email tab

  • Outlook Authentication Type: Ensure "OAuth2" is selected in this field. OAuth2 is used only in connection with MS Office365.
  • Outlook App ID - When you setup Azure you will populate this field, so the Azure setup must be done first
  • Outlook Tenant ID- When you setup Azure you will populate this field, so the Azure setup must be done first.
  • Outlook Secret - Optional. When you setup Azure you will populate this field, so the Azure setup must be done first.

In Main Menu > User Icon > Email Settings:

The email information below is the email associated with the Azure account.

  • Email -required.
  • Email Userrequired.
  • Email Passwordnot required (beginning in version 17.01.081) when using OAuth2 authentication.

Notes:

  1. The remaining fields on the Email Settings form are optional.
  2. The Email Setting section above will need to be completed for each user that will email from Deacom.

Additional Notes

  • Sending emails in Deacom - Emails can be sent from within Deacom from multiple locations and within multiple forms. The two most common locations/forms that offer the ability to send email are:
    • The Documents form, which is accessed via the View Docs* button located on multiple records and maintenance tabs within DEACOM. The Documents form is used to both upload documents and email those documents via the "Send Email" button.
    • The "Send Email" button on lot implosion reports in Inventory Reporting.
  • Single Sign-On Methods - Single sign-on methods are separate from email configuration and use in Deacom and not required. However, companies will often utilize the features of Single Sign-On Methods in Deacom.
  • Token Storage/Creation for OAuth2 - The system was enhanced (beginning in version 17.01.081) to reduce unnecessary and frequent authorization for the users. When the user's credentials are needed, the system will check the Authorization Expiration and Date (us_authexp date/time) fields to see if a new authorization is needed, otherwise, the system use the stored token from the database to update the session. If a new token is needed, the system will obtain the token following the process for OAuth2 and update both the session and and fields in Users (dxuser) table as appropriate. In addition, the Email Password field on the user record is no longer required when using OAuth2. This field will be store the token. If a user tries to send an email and there is no working token (either no token or an expired one), the system will launch a Microsoft form to enter O365 credentials. When complete and the form closes, the system will store the token and allow the user to click send again. The system will use this token until it expires, then, the next time it expires, repeats the same process.
  • Testing Azure SSO and emailing in multiple Deacom systems. Users may wish to setup more than one URL (representing a Deacom system) so they can test Azure SSO email configuration and setup. To do this, go to the "Authentication" section in the Azure admin site and click the "Add a platform" button to add as many add as many URL (Deacom systems) as desired. Note that in each of those Deacom systems you will still need to perform the Azure setup and configuration listed in steps 1-17 above.